Blocking — feature not honored on agentcore deploy.

ContainerPackager is only used by agentcore package (local validation) and agentcore dev. The actual deploy path goes through the CDK construct (@aws/agentcore-cdk), where:

• ContainerSourceAsset (in agentcore-l3-cdk-constructs) uploads only resolveCodeLocation(spec.codeLocation, configRoot) as the source asset — buildContextPath is never read, so files referenced from outside codeLocation won't be uploaded.
• ContainerBuildProject's buildspec hard-codes docker build -t $IMAGE_URI -f $DOCKERFILE_PATH . with no --build-arg plumbing.
• The L3 construct's own AgentEnvSpec schema doesn't include these new fields, so zod will strip them on the construct side anyway.

This means the documented "Shared Dockerfile (monorepo)" workflow in docs/container-builds.md will work locally and silently break (or behave wrongly) on deploy. That is a serious foot-gun.

Options to address:

1. (Preferred) Land a paired change in aws/agentcore-l3-cdk-constructs first that:
   • Adds buildContextPath and customDockerBuildArgs to AgentEnvSpecSchema.
   • Updates ContainerSourceAsset to upload buildContextPath (when set) instead of codeLocation, and adjusts the dockerfile path so it remains valid relative to that asset.
   • Updates ContainerBuildProject's buildspec / ContainerImageBuilder to forward --build-arg flags through CodeBuild env vars (e.g. via the custom resource properties, with the buildspec interpolating $BUILD_ARGS).
   • Bumps the construct dep here once published.
2. Hold this PR until that construct change is merged + published, and gate the schema additions in this repo on having the new construct version.
3. As an interim, validate in the CLI's schema (or in the deploy command) that these fields are not set and reject with a clear "only supported for local dev/package" error — but that significantly waters down the feature and the docs example would have to be removed.

I'd lean towards option 1. Happy to help review the construct-side PR.

Tied to the deploy issue: this example will not work end-to-end with agentcore deploy until the CDK construct side is updated. If we go with the "land construct first" path that's fine; otherwise this doc section should be reworded to make clear this is local-dev-only, or removed.

Separate issue with this example regardless of the deploy plumbing: dockerfile is validated as a filename (no path separators — see src/schema/schemas/agent-env.ts and getDockerfilePath in src/lib/constants.ts), and getDockerfilePath joins it onto codeLocation. So the implied "single Dockerfile at the project root" setup isn't achievable today — each agent's codeLocation would still need its own Dockerfile file (even if it's just a one-liner that delegates).

Either (a) extend dockerfile to accept a path relative to the build context (and resolve it accordingly), or (b) update this section to clarify that each codeLocation must still contain a Dockerfile (which can simply be a thin wrapper / symlink) and adjust the example accordingly.

Optional, but worth considering: the existing AgentEnvSpecSchema in the sibling construct repo already has a comment near this validator block (If adding more Container-specific fields, consider consolidating into a containerConfig object (see networkConfig pattern)). With this PR we're now up to three flat container-only fields (dockerfile, buildContextPath, customDockerBuildArgs) plus the cross-cutting validators. Grouping these under a single optional containerConfig: { dockerfile?, buildContextPath?, customDockerBuildArgs? } would make the cross-build-type validation simpler (build !== 'Container' && data.containerConfig becomes one check) and is more future-proof. Not strictly required for this PR, but if you agree it's worth doing it now before this ships.

[Blocker — correctness] dev crashes instead of reporting a config error.

ensureBuildContextDockerignore(buildContext) runs here inside prepare(), before the graceful missing-Dockerfile guard below, and calls writeFileSync with no try/catch. A buildContextPath that resolves to a missing or read-only directory throws ENOENT/EACCES, so prepare() never returns false — the throw propagates through await this.prepare(). In the TUI, useDevServer fires void startServer() with no catch around await server.start(), so this becomes an unhandled rejection that crashes the dev process; the web-ui path degrades to a generic 500 instead of the {success:false} handling the if (!child) block provides.

Shares a root cause with the preflight and packager comments: make ensureBuildContextDockerignore guard the directory's existence and run it after validation, via a shared notification callback.

[Blocker — correctness] Preflight masks its own friendly error and writes into the repo on a failing deploy.

ensureBuildContextDockerignore guards only the .dockerignore file's existence, never the directory. With buildContextPath: './typo-dir' (missing), the loop first pushes a clean "Dockerfile not found" into errors[], but this call then writeFileSyncs into the missing dir and throws raw ENOENT before the aggregated throw — so the user sees a cryptic fs error instead of the actionable one. When the dir exists but the Dockerfile is missing, it still leaves a stray .dockerignore in the repo even though the deploy aborts (dirtying CI/git checkouts).

Note the inconsistency with ContainerPackager.pack(), which does the Dockerfile existsSync check after this write; preflight does it before. Fix both by guarding the dir and deferring the write until validation passes.

[Blocker — correctness] package throws an untyped fs error and leaves a stray .dockerignore.

pack() calls ensureBuildContextDockerignore here, before the existsSync(dockerfilePath) check that used to be its first guard. A bad buildContextPath throws a bare Error (ENOENT), bypassing the PackagingError path — telemetry's classifyError only maps BaseError, so it lands in UnknownError and the user sees a cryptic message. With a valid dir but a missing Dockerfile, the .dockerignore is written into the repo before pack() rejects.

Same root cause as the dev-server and preflight comments. Also: preflight validates the Dockerfile before this write, so the two callers are inconsistent — centralize the ordering.

[Blocker — correctness] Generated .dockerignore doesn't exclude nested node_modules/secrets in the monorepo case.

These patterns (node_modules/, .venv/, __pycache__/, .env, ...) have no **/ prefix. Docker matches .dockerignore root-relative via Go filepath.Match, so node_modules/ matches only the top-level directory. In the feature's headline case (buildContextPath: '.'), nested app/agent-one/node_modules and per-package .env files are still uploaded to the Docker context and CodeBuild — directly contradicting the module/inline comments that this keeps secrets and build junk out of the upload. A leaked nested .env is security-adjacent, not just a size regression.

Use **/node_modules, **/.env, **/__pycache__, etc.

[Cleanup — reuse/altitude] Dockerfile-path validation is duplicated and already divergent.

The same "relative subpath, no leading slash, no backslash, no .." rule is now maintained in two places this PR edits in lockstep: this runtime guard in getDockerfilePath and the Zod DockerfilePathSchema regex+refine in agent-env.ts. They already disagree — the schema's ^[a-zA-Z0-9] anchor rejects .docker/Dockerfile, but this guard accepts it (no leading /, no \, no .. segment). Extract a single isValidDockerfilePath predicate used by both. Non-blocking, but worth doing while this code is open since the divergence is live.

[Cleanup — altitude] Build-context resolution re-derived at 4 sites with two different resolvers.

buildContextPath ?? codeLocation (then resolve) is re-implemented here, in preflight.ts (~line 210), and in container-dev-server.ts (~line 70) — while dev/config.ts resolves via a different private function (resolveCodeDirectory, which strips trailing slashes and uses join) than deploy/package (resolveCodeLocation, which uses resolve). The PR's own comments insist all paths must resolve context identically, so this is a latent local-vs-deploy divergence: a future path-normalization tweak applied to one resolver silently makes agentcore dev build from a different context than deploy. Collapse into one exported resolveBuildContext(spec, baseDir). Non-blocking.

[Cleanup — reuse] BuildArgKeySchema re-declares EnvVarNameSchema's regex.

This regex /^[A-Za-z_][A-Za-z0-9_]*$/ is byte-identical to the exported EnvVarNameSchema above. Build args become CodeBuild env-var names, so reuse EnvVarNameSchema (with a custom message) — nothing is lost, since the RESERVED_BUILD_ARG_KEYS check lives separately in the superRefine. Non-blocking.

[Cleanup — low severity] Broadened dockerfile regex accepts a directory-shaped value.

Widening the regex to allow / for subpaths also lets a trailing-slash directory value like docker/ through (docker/Dockerfile/ and a//b are caught cleanly by existsSync/join normalization, but a value naming a real directory is not). That defers failure to docker build -f <dir> with a confusing error instead of rejecting at config-validation time. Low severity; a .refine rejecting a trailing slash closes it.